pinokiod 8.1.0 → 8.1.1

package/kernel/api/env/index.js

@@ -15,7 +15,7 @@ class Env {
       }
     */
     // write to current app folder's ENVIRONMENT
-    let api_path = Util.api_path(req.parent.path, kernel)
+    let api_path = await kernel.api.launcher_path(Util.api_path(req.parent.path, kernel))
     let env_path = path.resolve(api_path, "ENVIRONMENT")
     await Util.update_env(env_path, req.params)
   }
@@ -35,7 +35,7 @@ class Env {
         }
       }
     */
-    let api_path = Util.api_path(req.parent.path, kernel)
+    let api_path = await kernel.api.launcher_path(Util.api_path(req.parent.path, kernel))
     let env_path = path.resolve(api_path, "ENVIRONMENT")
     let env = await Environment.get2(req.parent.path, kernel)
     // does the key exist?

package/kernel/api/index.js

@@ -131,7 +131,7 @@ class Api {
     if (formData.icon_dirty) {
       // 
       // write icon file
-      let icon_path = this.kernel.path("api", formData.new_path, formData.icon_path)
+      let icon_path = path.resolve(launcher_path, formData.icon_path)
       await fs.promises.writeFile(icon_path, formData.avatar)
       meta.icon = formData.icon_path
       dirty = true
@@ -232,7 +232,7 @@ class Api {
       meta.ui = `/p/${api_name}`
       meta.browse = `/p/${api_name}/dev`
     } else {
-      meta.icon = meta.icon ? `/asset/api/${api_name}/${meta.icon}` : "/pinokio-black.png"
+      Util.NestedLayout.setMetaIcon(meta, api_name, api_root_path, relpath, isWithinApiRoot)
       meta.link = `/p/${api_name}/${relpath}/dev#n1`
       meta.web_path = `/api/${api_name}/${relpath}`
       meta.ui = `/p/${api_name}/${relpath}`
@@ -1791,6 +1791,7 @@ class Api {
     })
   }
   async get_default(repo_path) {
+    repo_path = await this.launcher_path(repo_path)
     let launcher = await this.launcher({
       path: repo_path
     })
@@ -1882,7 +1883,7 @@ class Api {
       if (chunks.length == 2) {
         // the script is requesting a uri of the git repo
         // look for pinokio.js
-        let p = path.resolve(request.path, "pinokio.js")
+        let p = path.resolve(await this.launcher_path(request.path), "pinokio.js")
         let exists = await this.exists(p)
         if (exists) {
           await this.launch(request, p)

package/kernel/api/launcher_target.js

@@ -109,6 +109,7 @@ const loadMenu = async (api, repoPath) => {
 }
 
 module.exports = async (api, repoPath, preferred = []) => {
+  repoPath = await api.launcher_path(repoPath)
   let defaultTarget = await api.get_default(repoPath)
   if (defaultTarget) {
     return {

package/kernel/app_log_sessions.js

@@ -3,6 +3,7 @@ const path = require('path')
 const crypto = require('crypto')
 const { AsyncLocalStorage } = require('async_hooks')
 const Environment = require('./environment')
+const NestedLayout = require('./nested_layout')
 
 class AppLogSessions {
   constructor({ kernel, now = () => new Date().toISOString(), randomHex = () => crypto.randomBytes(3).toString('hex') }) {
@@ -90,7 +91,7 @@ class AppLogSessions {
     return {
       appRoot,
       scriptPath: absolute,
-      script: this.toPosix(parts.slice(1).join(path.sep))
+      script: this.toPosix(await NestedLayout.sessionScript(this, apiRoot, appRoot, absolute, parts.slice(1).join(path.sep)))
     }
   }
 

package/kernel/environment.js

@@ -660,7 +660,7 @@ const get = async (homedir, kernel) => {
   for(let key in current_env) {
     let val = current_env[key]
     if (val.startsWith("./")) {
-      let full_path = path.resolve(homedir, val)
+      let full_path = await Util.NestedLayout.environmentPath(kernel, homedir, val, got_root)
       current_env[key] = full_path
     }
     if (val.trim() === "") {
@@ -1013,6 +1013,7 @@ const init = async (options, kernel) => {
       await fs.promises.appendFile(excludePath, appendContent)
     }
   }
+  await Util.NestedLayout.ensureGitExclude(root, relpath, kernel)
   return {
     relpath,
     root_path: root,

package/kernel/nested_layout.js

@@ -0,0 +1,140 @@
+const fs = require('fs')
+const path = require('path')
+
+const samePath = (left, right) => path.resolve(left) === path.resolve(right)
+
+const launcherPath = async (kernel, workspace) => {
+  if (!kernel.api || typeof kernel.api.launcher_path !== 'function') return workspace
+  return kernel.api.launcher_path(workspace)
+}
+
+const relativeRoot = async (kernel, workspace) => path.relative(workspace, await launcherPath(kernel, workspace))
+
+const menuRoot = async (kernel, workspace, legacyRoot) => {
+  if (!legacyRoot) return ''
+  return samePath(await launcherPath(kernel, workspace), path.resolve(workspace, legacyRoot)) ? legacyRoot : ''
+}
+
+const environmentPath = async (kernel, homedir, value, root) => {
+  const base = root.relpath ? await launcherPath(kernel, homedir) : homedir
+  return path.resolve(base, value)
+}
+
+const sessionScript = async (sessions, apiRoot, appRoot, scriptPath, fallback) => {
+  const workspace = path.resolve(apiRoot, path.relative(apiRoot, scriptPath).split(path.sep)[0])
+  if (samePath(appRoot, workspace)) return fallback
+  const root = await launcherPath(sessions.kernel, workspace)
+  return sessions.isPathWithin(root, scriptPath) ? path.relative(root, scriptPath) : fallback
+}
+
+const logScript = async (kernel, scriptPath, relativeParts) => {
+  const fallback = relativeParts.slice(2)
+  if (relativeParts[2] !== 'pinokio') return fallback
+  const root = await launcherPath(kernel, kernel.path(...relativeParts.slice(0, 2)))
+  const relative = path.relative(root, scriptPath)
+  return relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative) ? fallback : relative.split(path.sep).filter(Boolean)
+}
+
+const appLogValues = async (registry, appRoot, scriptQuery, runtimeScripts) => {
+  const root = await launcherPath(registry.kernel || {}, appRoot)
+  if (samePath(root, appRoot)) return { appRoot, scriptQuery, runtimeScripts }
+  const strip = value => typeof value === 'string' ? value.replace(/^pinokio[\\/]/, '') : value
+  return { appRoot: root, scriptQuery: strip(scriptQuery), runtimeScripts: runtimeScripts.map(strip) }
+}
+
+const appScripts = async (registry, appRoot) => {
+  const root = await launcherPath(registry.kernel, appRoot)
+  const prefix = path.relative(appRoot, root).split(path.sep).join('/')
+  const candidates = files => files.map(file => path.posix.join(prefix, file))
+  return {
+    installScript: await registry.firstExistingScript(appRoot, candidates(['install.js', 'install.json'])),
+    startScript: await registry.firstExistingScript(appRoot, candidates(['start.js', 'start.json']))
+  }
+}
+
+const addSearchCandidates = async (search, appRoot, candidates) => {
+  const root = await launcherPath(search.kernel, appRoot)
+  if (samePath(root, appRoot)) return
+  const prefix = path.relative(appRoot, root).split(path.sep).join('/')
+  const seen = new Set(candidates.map(candidate => candidate.relativePath))
+  for (const candidate of await search.collectAppSearchCandidates(root)) {
+    const relativePath = `${prefix}/${candidate.relativePath}`
+    if (!seen.has(relativePath)) candidates.push({ ...candidate, relativePath })
+  }
+}
+
+const setMetaIcon = (meta, apiName, apiRoot, relpath, isWithinApiRoot) => {
+  const prefix = relpath.split(path.sep).join('/') === 'pinokio' && isWithinApiRoot(apiRoot) ? 'pinokio/' : ''
+  meta.icon = meta.icon ? `/asset/api/${apiName}/${prefix}${meta.icon}` : '/pinokio-black.png'
+  if (prefix && meta.iconpath) meta.iconpath = `${prefix}${meta.iconpath}`
+}
+
+const preLauncher = async (kernel, launcher) => {
+  const root = await launcherPath(kernel, launcher.root)
+  if (samePath(root, launcher.root) || !launcher.script || !Array.isArray(launcher.script.pre)) return launcher
+  const prefix = path.relative(launcher.root, root).split(path.sep).join('/')
+  const pre = launcher.script.pre.map(item => {
+    if (!item || typeof item !== 'object') return item
+    const copy = { ...item }
+    if (typeof copy.icon === 'string' && copy.icon) copy.icon = `${prefix}/${copy.icon}`
+    if (typeof copy.href === 'string' && copy.href && !copy.href.startsWith('http')) copy.href = path.resolve(root, copy.href)
+    return copy
+  })
+  return { ...launcher, root, script: { ...launcher.script, pre } }
+}
+
+const addAiFiles = async (kernel, workspace, filenames, files, exists) => {
+  const root = await launcherPath(kernel, workspace)
+  if (samePath(root, workspace)) return files
+  for (const filename of filenames) {
+    const candidate = path.resolve(root, filename)
+    const relative = path.relative(workspace, candidate).split(path.sep).join('/')
+    if (!files.includes(relative) && await exists(candidate)) files.push(relative)
+  }
+  return files
+}
+
+// Keep in sync with the legacy list in Environment.init.
+const excludeEntries = [
+  'ENVIRONMENT', '/.pinokio-temp', '/logs', '/cache', '/AGENTS.md',
+  '/CLAUDE.md', '/GEMINI.md', '/QWEN.md', '/.geminiignore',
+  '.clinerules', '.cursorrules', '.windsurfrules'
+]
+
+const ensureGitExclude = async (root, relpath, kernel) => {
+  if (!relpath || !samePath(await launcherPath(kernel, path.dirname(root)), root)) return
+  const workspace = path.dirname(root)
+  const gitDir = path.resolve(workspace, '.git')
+  try {
+    if (!(await fs.promises.stat(gitDir)).isDirectory()) return
+    const excludePath = path.resolve(gitDir, 'info', 'exclude')
+    let content = ''
+    try {
+      content = await fs.promises.readFile(excludePath, 'utf8')
+    } catch (error) {
+      if (error.code !== 'ENOENT') return
+    }
+    const existing = new Set(content.split(/\r?\n/).map(line => line.trim()).filter(Boolean))
+    const prefix = path.relative(workspace, root).split(path.sep).join('/')
+    const missing = excludeEntries.map(entry => `/${prefix}/${entry.replace(/^\//, '')}`).filter(entry => !existing.has(entry))
+    if (!missing.length) return
+    await fs.promises.mkdir(path.dirname(excludePath), { recursive: true })
+    await fs.promises.appendFile(excludePath, `${content && !content.endsWith('\n') ? '\n' : ''}${missing.join('\n')}\n`)
+  } catch (_) {
+  }
+}
+
+module.exports = {
+  addAiFiles,
+  addSearchCandidates,
+  appLogValues,
+  appScripts,
+  ensureGitExclude,
+  environmentPath,
+  logScript,
+  menuRoot,
+  preLauncher,
+  relativeRoot,
+  sessionScript,
+  setMetaIcon
+}

package/kernel/util.js

@@ -1246,6 +1246,7 @@ const rewrite_localhost= (kernel, obj, source) => {
 
 
 module.exports = {
+  NestedLayout: require('./nested_layout'),
   parse_env,
   log_path,
   api_path,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pinokiod",
-  "version": "8.1.0",
+  "version": "8.1.1",
   "description": "",
   "main": "index.js",
   "scripts": {

package/server/autolaunch.js

@@ -406,7 +406,7 @@ class ServerAutolaunch {
         if (!localScript) {
           continue
         }
-        const scriptPath = path.resolve(launcherRoot, localScript)
+        const scriptPath = path.resolve(app.launcher_root && menuitem.href.trim().startsWith(apiPrefix) ? appRoot : launcherRoot, localScript)
         if (!this.server.is_subpath(appRoot, scriptPath)) {
           continue
         }

package/server/index.js

@@ -3861,7 +3861,7 @@ class Server {
                   config.shortcuts = config.shortcuts(this.kernel, this.kernel.info)
                 }
               }
-              await this.renderShortcuts(uri, item.name, config, pathComponents)
+              await this.renderShortcuts(uri, item.name, config, pathComponents, await Util.NestedLayout.relativeRoot(this.kernel, this.kernel.path("api", item.name)))
               items[i].shortcuts = config.shortcuts
             }
           }
@@ -4369,14 +4369,14 @@ class Server {
 
     }
   }
-  async renderShortcuts(uri, name, config, pathComponents) {
+  async renderShortcuts(uri, name, config, pathComponents, launcher_root = "") {
     if (config.shortcuts) {
       for(let i=0; i<config.shortcuts.length; i++) {
         let shortcut = config.shortcuts[i]
         if (shortcut.action) {
           if (shortcut.action.method === "stop") {
             if (shortcut.action.uri) {
-              let absolute = path.resolve(__dirname, ...pathComponents, shortcut.action.uri)
+              let absolute = path.resolve(__dirname, launcher_root, ...pathComponents, shortcut.action.uri)
               let seed = path.resolve(__dirname)
               let p = absolute.replace(seed, "")
               let link = p.split(/[\/\\]/).filter((x) => { return x }).join("/")
@@ -4584,6 +4584,7 @@ class Server {
 //      }].concat(config.menu)
 
       let launcher_root = req.launcher_root || ""
+      let nested_root = await Util.NestedLayout.menuRoot(this.kernel, path.resolve(uri, name), launcher_root)
 
       for(let i=0; i<config.menu.length; i++) {
         let menuitem = config.menu[i]
@@ -4640,7 +4641,7 @@ class Server {
               }
             } else {
               config.menu[i].run = rendered.run
-              config.menu[i].cwd = path.resolve(this.kernel.homedir, "api", launcher_root, name)
+              config.menu[i].cwd = nested_root ? path.resolve(this.kernel.homedir, "api", name, nested_root) : path.resolve(this.kernel.homedir, "api", launcher_root, name)
               if (launcher_root) {
                 config.menu[i].href = "/api/" + name + "/" + launcher_root
               } else {
@@ -4749,7 +4750,7 @@ class Server {
         if (menuitem.action) {
           if (menuitem.action.method === "stop") {
             if (menuitem.action.uri) {
-              let absolute = path.resolve(__dirname, ...pathComponents, menuitem.action.uri)
+              let absolute = path.resolve(__dirname, nested_root, ...pathComponents, menuitem.action.uri)
               let seed = path.resolve(__dirname)
               let p = absolute.replace(seed, "")
               let link = p.split(/[\/\\]/).filter((x) => { return x }).join("/")
@@ -4773,7 +4774,7 @@ class Server {
         // check on/off: if on/off exists => assume that it's a script
         // 1. check if the script is running
         if (menuitem.when) {
-          let scriptPath = path.resolve(uri, name, menuitem.when)
+          let scriptPath = path.resolve(uri, name, nested_root, menuitem.when)
           let filepath = scriptPath.replace(/\?.+/, "")
           let check = this.kernel.status(filepath)
           if (check) {
@@ -5227,7 +5228,7 @@ class Server {
       if (!workspaceStats.isDirectory()) {
         throw new Error('Workspace path is not a directory')
       }
-      const candidate = path.resolve(workspacePath, 'logs')
+      const candidate = path.resolve(await this.kernel.api.launcher_path(workspacePath), 'logs')
       await fs.promises.mkdir(candidate, { recursive: true })
       return {
         logsRoot: candidate,
@@ -14677,7 +14678,7 @@ class Server {
 //      }
 //    }))
     this.app.post("/env", ex(async (req, res) => {
-      let fullpath = path.resolve(this.kernel.homedir, req.body.filepath, "ENVIRONMENT")
+      let fullpath = path.resolve(await this.kernel.api.launcher_path(path.resolve(this.kernel.homedir, req.body.filepath)), "ENVIRONMENT")
       let updated = req.body.vals
       let hosts = req.body.hosts
       await Util.update_env(fullpath, updated)
@@ -14830,7 +14831,7 @@ class Server {
       //})
     }))
     this.app.get("/pre/api/:name", ex(async (req, res) => {
-      let launcher = await this.kernel.api.launcher(req.params.name)
+      let launcher = await Util.NestedLayout.preLauncher(this.kernel, await this.kernel.api.launcher(req.params.name))
       let config = launcher.script
       if (config && Array.isArray(config.pre)) {
         const items = config.pre.filter((item) => item && typeof item === "object")
@@ -14888,7 +14889,7 @@ class Server {
       }
     }))
     this.app.get("/share/:name", ex(async (req, res) => {
-      let filepath = path.resolve(this.kernel.homedir, "api", req.params.name, "ENVIRONMENT")
+      let filepath = path.resolve(await this.kernel.api.launcher_path(req.params.name), "ENVIRONMENT")
       //let filepath = path.resolve(this.kernel.homedir, req.params[0])
       const config = await Util.parse_env(filepath)
       const keys = [
@@ -15640,10 +15641,11 @@ class Server {
           files.push(filename)
         }
       }
+      files = await Util.NestedLayout.addAiFiles(this.kernel, this.kernel.path("api", req.params.name), filenames, files, this.exists.bind(this))
 
       let items = files.map((item) => {
         return {
-          text: item,
+          text: path.basename(item),
           href: `/_api/${req.params.name}/${item}`
         }
       })

package/server/lib/app_logs.js

@@ -1,5 +1,6 @@
 const fs = require('fs')
 const path = require('path')
+const NestedLayout = require('../../kernel/nested_layout')
 
 class AppLogService {
   constructor({ registry }) {
@@ -38,6 +39,7 @@ class AppLogService {
   }
 
   async resolveAppLogFile(appRoot, scriptQuery = '', runtimeScripts = []) {
+    ({ appRoot, scriptQuery, runtimeScripts } = await NestedLayout.appLogValues(this.registry, appRoot, scriptQuery, runtimeScripts))
     const apiLogsRoot = path.resolve(appRoot, 'logs', 'api')
     const candidates = []
     const addCandidate = (value) => {

package/server/lib/app_registry.js

@@ -412,8 +412,7 @@ class AppRegistryService {
 
     const runtime = this.collectAppRuntime(appRoot)
     runtime.external_ready_urls = this.buildExternalReadyUrls(runtime.ready_url, options.source || null)
-    const installScript = await this.firstExistingScript(appRoot, ['install.js', 'install.json'])
-    const startScript = await this.firstExistingScript(appRoot, ['start.js', 'start.json'])
+    const { installScript, startScript } = await Util.NestedLayout.appScripts(this, appRoot)
     let defaultTarget = null
     try {
       defaultTarget = await this.kernel.api.get_default(appRoot)

package/server/lib/app_search.js

@@ -2,6 +2,7 @@ const fs = require('fs')
 const path = require('path')
 const crypto = require('crypto')
 const MiniSearch = require('minisearch')
+const NestedLayout = require('../../kernel/nested_layout')
 
 const APP_SEARCH_CACHE_TTL_MS = 15000
 const APP_SEARCH_MAX_FILE_BYTES = 1024 * 1024
@@ -265,6 +266,7 @@ class AppSearchService {
     for (const app of apps) {
       const appRoot = this.kernel.path('api', app.name)
       const candidates = await this.collectAppSearchCandidates(appRoot)
+      await NestedLayout.addSearchCandidates(this, appRoot, candidates)
       const fingerprint = this.computeAppSearchFingerprint(app, candidates)
       const previous = previousPerApp.get(app.name)
       let appDocs

package/server/socket.js

@@ -729,8 +729,8 @@ class Socket {
       if (relative === null) return null
       let relative_parts = relative.split(path.sep).filter(Boolean)
       if (relative_parts[0] === "api" && relative_parts[1]) {
-        let filepath_chunks = relative_parts.slice(2)
         let cwd = this.parent.kernel.path(...relative_parts.slice(0, 2))
+        let filepath_chunks = await Util.NestedLayout.logScript(this.parent.kernel, p, relative_parts)
         let root = await Environment.get_root({ path: cwd }, this.parent.kernel)
         cwd = root.root
         return path.resolve(cwd, "logs/api", ...filepath_chunks)

package/test/nested-launcher-parity.test.js

@@ -0,0 +1,342 @@
+const assert = require('node:assert/strict')
+const fs = require('node:fs/promises')
+const os = require('node:os')
+const path = require('node:path')
+const test = require('node:test')
+
+const Api = require('../kernel/api')
+const Env = require('../kernel/api/env')
+const Environment = require('../kernel/environment')
+const NestedLayout = require('../kernel/nested_layout')
+const getLauncherTarget = require('../kernel/api/launcher_target')
+const AppLogSessions = require('../kernel/app_log_sessions')
+const Server = require('../server')
+const ServerAutolaunch = require('../server/autolaunch')
+const Socket = require('../server/socket')
+const AppLogService = require('../server/lib/app_logs')
+const AppLogReportService = require('../server/lib/app_log_report')
+const AppRegistryService = require('../server/lib/app_registry')
+const AppSearchService = require('../server/lib/app_search')
+
+const exists = target => fs.access(target).then(() => true, () => false)
+
+const kernelFor = home => {
+  const loaded = new Map()
+  const kernel = {
+    homedir: home,
+    path: (...parts) => path.resolve(home, ...parts),
+    exists,
+    status: () => false,
+    template: { render: value => value },
+    memory: { local: {} },
+    loader: { load: async target => ({ resolved: loaded.get(path.resolve(target)) || null }) }
+  }
+  kernel.api = new Api(kernel)
+  kernel.api.userdir = path.resolve(home, 'api')
+  kernel.api.exists = exists
+  kernel.api.running = {}
+  kernel.loaded = loaded
+  return kernel
+}
+
+const withHome = async callback => {
+  const home = await fs.mkdtemp(path.join(os.tmpdir(), 'pinokio-nested-parity-'))
+  try {
+    await callback(home)
+  } finally {
+    await fs.rm(home, { recursive: true, force: true })
+  }
+}
+
+const write = async (root, relative, content = '') => {
+  const target = path.resolve(root, relative)
+  await fs.mkdir(path.dirname(target), { recursive: true })
+  await fs.writeFile(target, content)
+  return target
+}
+
+test('root launcher precedence and environment writes remain unchanged', async () => {
+  await withHome(async home => {
+    const kernel = kernelFor(home)
+    const env = new Env()
+    const layouts = [
+      ['classic', ['pinokio.js']],
+      ['root-with-folder', ['pinokio.js', 'pinokio/note.txt']],
+      ['both', ['pinokio.js', 'pinokio/pinokio.js']],
+      ['empty-folder', ['pinokio/note.txt']],
+      ['no-manifest', []]
+    ]
+
+    for (const [name, files] of layouts) {
+      const workspace = path.resolve(home, 'api', name)
+      await fs.mkdir(workspace, { recursive: true })
+      for (const file of files) await write(workspace, file)
+      await write(workspace, 'ENVIRONMENT')
+      assert.equal(await kernel.api.launcher_path(workspace), workspace, name)
+      if (files.includes('pinokio.js')) kernel.loaded.set(path.resolve(workspace, 'pinokio.js'), { icon: 'icon.png' })
+      const meta = await kernel.api.meta(name)
+      if (files.includes('pinokio.js')) {
+        assert.equal(meta.icon, `/asset/api/${name}/icon.png`, name)
+        assert.equal(meta.iconpath, 'icon.png', name)
+      }
+      await env.set({ parent: { path: path.resolve(workspace, 'start.js') }, params: { VALUE: name } }, null, kernel)
+      assert.match(await fs.readFile(path.resolve(workspace, 'ENVIRONMENT'), 'utf8'), new RegExp(`VALUE=${name}`), name)
+    }
+
+    const pinokioEntry = path.resolve(home, 'api', 'pinokio-entry')
+    await fs.mkdir(pinokioEntry, { recursive: true })
+    await write(pinokioEntry, 'pinokio')
+    await write(pinokioEntry, 'ENVIRONMENT')
+    assert.equal(await kernel.api.launcher_path(pinokioEntry), pinokioEntry)
+    await env.set({ parent: { path: path.resolve(pinokioEntry, 'start.js') }, params: { VALUE: 'file' } }, null, kernel)
+    assert.match(await fs.readFile(path.resolve(pinokioEntry, 'ENVIRONMENT'), 'utf8'), /VALUE=file/)
+  })
+})
+
+test('nested launcher environment, metadata, targets, registry, and search use pinokio/', async () => {
+  await withHome(async home => {
+    const kernel = kernelFor(home)
+    const workspace = path.resolve(home, 'api', 'nested')
+    const launcher = path.resolve(workspace, 'pinokio')
+    const launcherConfig = { title: 'Nested', icon: 'icon.png', menu: [
+      { text: 'Start', href: 'start.js', default: true },
+      { text: 'Nested child', href: 'pinokio/tool.js' },
+      { text: 'Absolute nested', href: '/api/nested/pinokio/absolute.js' },
+      { text: 'Absolute workspace', href: '/api/nested/workspace.js' }
+    ] }
+    await write(workspace, 'README.md', 'workspace documentation')
+    await write(launcher, 'README.md', 'launcher documentation')
+    await write(launcher, 'pinokio.js', 'nested launcher token')
+    await write(launcher, 'install.js', 'nested install token')
+    await write(launcher, 'start.js', 'nested start token')
+    await write(launcher, 'pinokio/tool.js', 'nested child token')
+    await write(launcher, 'absolute.js', 'absolute nested token')
+    await write(workspace, 'workspace.js', 'absolute workspace token')
+    await write(launcher, 'ENVIRONMENT', 'DATA=./data\nVALUE=old\n')
+    kernel.loaded.set(path.resolve(launcher, 'pinokio.js'), launcherConfig)
+
+    assert.equal(await kernel.api.launcher_path(workspace), launcher)
+    assert.equal((await Environment.get(workspace, kernel)).DATA, path.resolve(launcher, 'data'))
+
+    await new Env().set({ parent: { path: path.resolve(launcher, 'start.js') }, params: { VALUE: 'nested' } }, null, kernel)
+    assert.match(await fs.readFile(path.resolve(launcher, 'ENVIRONMENT'), 'utf8'), /VALUE=nested/)
+
+    const meta = await kernel.api.meta('nested')
+    assert.equal(meta.icon, '/asset/api/nested/pinokio/icon.png')
+    assert.equal(meta.iconpath, 'pinokio/icon.png')
+    assert.equal(await kernel.api.get_default(workspace), path.resolve(launcher, 'start.js'))
+    assert.equal((await getLauncherTarget(kernel.api, workspace, ['start.js'])).uri, path.resolve(launcher, 'start.js'))
+
+    const registry = new AppRegistryService({ kernel })
+    const status = await registry.buildAppStatus('nested')
+    assert.equal(status.install_script, 'pinokio/install.js')
+    assert.equal(status.start_script, 'pinokio/start.js')
+    assert.equal(status.default_script, 'pinokio/start.js')
+
+    const searchRegistry = {
+      listInfoApps: async () => [{ name: 'nested', title: 'Nested', description: '', icon: '' }],
+      isPathWithin: registry.isPathWithin.bind(registry)
+    }
+    const state = await new AppSearchService({ kernel, registry: searchRegistry }).ensureSearchState(true)
+    const files = state.docs.map(doc => doc.file)
+    assert(files.includes('README.md'))
+    assert(files.includes('pinokio/pinokio.js'))
+    assert(files.includes('pinokio/install.js'))
+    assert(files.includes('pinokio/start.js'))
+    assert.equal(files.filter(file => file === 'pinokio/README.md').length, 1)
+
+    const server = Object.assign(Object.create(Server.prototype), { kernel })
+    const app = (await kernel.api.listApps()).find(item => item.id === 'nested')
+    const candidates = await new ServerAutolaunch(server).buildCandidates(app)
+    assert(candidates.menu.some(item => item.script === 'pinokio/start.js'))
+    assert(candidates.menu.some(item => item.script === 'pinokio/pinokio/tool.js'))
+    assert(candidates.menu.some(item => item.script === 'pinokio/absolute.js'))
+    assert(candidates.menu.some(item => item.script === 'workspace.js'))
+    assert(candidates.other.some(item => item.script === 'pinokio/install.js'))
+
+    await kernel.api.updateMeta({ icon_dirty: true, icon_path: 'uploaded.png', avatar: Buffer.from('icon') }, 'nested')
+    assert.equal(await fs.readFile(path.resolve(launcher, 'uploaded.png'), 'utf8'), 'icon')
+    assert.equal(await exists(path.resolve(workspace, 'uploaded.png')), false)
+  })
+})
+
+test('nested preflight assets and AI documents use pinokio/ without changing root launchers', async () => {
+  await withHome(async home => {
+    const kernel = kernelFor(home)
+    const nested = path.resolve(home, 'api', 'nested')
+    const nestedRoot = path.resolve(nested, 'pinokio')
+    await write(nestedRoot, 'pinokio.js')
+    await write(nestedRoot, 'CLAUDE.md')
+    await write(nested, 'CLAUDE.md')
+
+    const launcher = {
+      root: nested,
+      script: { pre: [{ icon: 'icon.png', href: 'setup.js' }, { href: 'https://example.com' }] }
+    }
+    const adapted = await NestedLayout.preLauncher(kernel, launcher)
+    assert.equal(adapted.root, nestedRoot)
+    assert.equal(adapted.script.pre[0].icon, 'pinokio/icon.png')
+    assert.equal(adapted.script.pre[0].href, path.resolve(nestedRoot, 'setup.js'))
+    assert.equal(adapted.script.pre[1].href, 'https://example.com')
+    assert.equal(launcher.script.pre[0].icon, 'icon.png')
+
+    const files = await NestedLayout.addAiFiles(kernel, nested, ['AGENTS.md', 'CLAUDE.md'], ['CLAUDE.md'], exists)
+    assert.deepEqual(files, ['CLAUDE.md', 'pinokio/CLAUDE.md'])
+
+    const root = path.resolve(home, 'api', 'root')
+    await write(root, 'pinokio.js')
+    await write(root, 'pinokio/pinokio.js')
+    const rootLauncher = { root, script: { pre: [{ icon: 'icon.png', href: 'setup.js' }] } }
+    const rootFiles = []
+    assert.equal(await NestedLayout.preLauncher(kernel, rootLauncher), rootLauncher)
+    assert.equal(await NestedLayout.addAiFiles(kernel, root, ['CLAUDE.md'], rootFiles, exists), rootFiles)
+    assert.deepEqual(rootFiles, [])
+
+    const iconpath = { invalid: true }
+    const rootMeta = { icon: iconpath, iconpath }
+    NestedLayout.setMetaIcon(rootMeta, 'root', root, '', () => true)
+    assert.strictEqual(rootMeta.iconpath, iconpath)
+  })
+})
+
+test('nested menus and shortcuts resolve relative paths from pinokio/', async () => {
+  await withHome(async home => {
+    const kernel = kernelFor(home)
+    const workspace = path.resolve(home, 'api', 'nested')
+    const launcher = path.resolve(workspace, 'pinokio')
+    await write(launcher, 'pinokio.js')
+    const checked = []
+    kernel.status = target => {
+      checked.push(target)
+      return false
+    }
+    const server = Object.assign(Object.create(Server.prototype), { kernel })
+    const config = {
+      menu: [
+        { text: 'Start', href: 'start.js' },
+        { text: 'Shell', run: 'echo ready' },
+        { text: 'Stop', action: { method: 'stop', uri: 'start.js' } },
+        { text: 'Absolute', action: { method: 'stop', uri: path.resolve('/abs', 'stop.js') } },
+        { text: 'State', when: 'start.js', off: 'off' }
+      ],
+      shortcuts: [
+        { action: { method: 'stop', uri: 'start.js' } },
+        { action: { method: 'stop', uri: path.resolve('/abs', 'stop.js') } }
+      ]
+    }
+
+    await server.renderMenu({ launcher_root: 'pinokio', $source: {} }, kernel.path('api'), 'nested', config, [])
+    assert.equal(config.menu[0].href, '/api/nested/pinokio/start.js')
+    assert.equal(config.menu[1].cwd, launcher)
+    assert.equal(config.menu[2].action.uri, '~/api/nested/pinokio/start.js')
+    assert.equal(config.menu[3].action.uri, '~/api/nested/abs/stop.js')
+    assert(checked.includes(path.resolve(launcher, 'start.js')))
+
+    await server.renderShortcuts(kernel.path('api'), 'nested', config, [], 'pinokio')
+    assert.equal(config.shortcuts[0].action.uri, '~/api/nested/pinokio/start.js')
+    assert.equal(config.shortcuts[1].action.uri, '~/api/nested/abs/stop.js')
+  })
+})
+
+test('root launcher load fallback keeps its legacy menu paths', async () => {
+  await withHome(async home => {
+    const kernel = kernelFor(home)
+    const workspace = path.resolve(home, 'api', 'fallback')
+    await write(workspace, 'pinokio.js')
+    await write(workspace, 'pinokio/pinokio.js')
+    await write(workspace, 'pinokio/start.js')
+    await write(workspace, 'pinokio.json')
+    kernel.loaded.set(path.resolve(workspace, 'pinokio/pinokio.js'), { menu: [] })
+    kernel.loaded.set(path.resolve(workspace, 'pinokio.json'), { menu: [{ href: '/api/fallback/start.js' }] })
+    const launcher = await kernel.api.launcher('fallback')
+    assert.equal(launcher.launcher_root, 'pinokio')
+    assert.equal(await kernel.api.launcher_path(workspace), workspace)
+
+    const checked = []
+    kernel.status = target => {
+      checked.push(target)
+      return false
+    }
+    const server = Object.assign(Object.create(Server.prototype), { kernel })
+    const config = {
+      menu: [
+        { text: 'Shell', run: 'echo ready' },
+        { text: 'Stop', action: { method: 'stop', uri: 'start.js' } },
+        { text: 'State', when: 'start.js', off: 'off' }
+      ],
+      shortcuts: [{ action: { method: 'stop', uri: 'start.js' } }]
+    }
+    await server.renderMenu({ launcher_root: launcher.launcher_root, $source: {} }, kernel.path('api'), 'fallback', config, [])
+    await server.renderShortcuts(kernel.path('api'), 'fallback', config, [], path.relative(workspace, await kernel.api.launcher_path(workspace)))
+
+    assert.equal(config.menu[0].cwd, path.resolve(home, 'api', 'pinokio', 'fallback'))
+    assert.equal(config.menu[1].action.uri, '~/api/fallback/start.js')
+    assert(checked.includes(path.resolve(workspace, 'start.js')))
+    assert.equal(config.shortcuts[0].action.uri, '~/api/fallback/start.js')
+
+    const app = (await kernel.api.listApps()).find(item => item.id === 'fallback')
+    const candidates = await new ServerAutolaunch(server).buildCandidates(app)
+    assert.equal(app.launcher_root, '')
+    assert(candidates.menu.some(item => item.script === 'pinokio/start.js'))
+  })
+})
+
+test('nested logs use launcher-relative paths in storage, display, and reports', async () => {
+  await withHome(async home => {
+    const kernel = kernelFor(home)
+    const workspace = path.resolve(home, 'api', 'nested')
+    const launcher = path.resolve(workspace, 'pinokio')
+    const script = await write(launcher, 'start.js')
+    await write(launcher, 'pinokio.js')
+
+    const socket = Object.assign(Object.create(Socket.prototype), { parent: { kernel } })
+    const logDir = await socket.resolveLogDir(script)
+    assert.equal(logDir, path.resolve(launcher, 'logs', 'api', 'start.js'))
+    const logFile = await write(logDir, 'latest', 'nested live content\n')
+    const sessionLog = await write(logDir, '123', 'nested report content\n')
+
+    const sessions = new AppLogSessions({ kernel, randomHex: () => 'nested' })
+    const run = await sessions.startRun({ path: script })
+    assert.equal(run.appRoot, launcher)
+    assert.equal(run.script, 'start.js')
+    await sessions.recordLogFile({ scriptPath: run.scriptPath, logFile: sessionLog, run })
+
+    const registry = new AppRegistryService({ kernel })
+    const selected = await new AppLogService({ registry }).resolveAppLogFile(workspace, '', ['pinokio/start.js'])
+    assert.equal(selected.script, 'start.js')
+    assert.equal(selected.file, logFile)
+
+    const server = Object.assign(Object.create(Server.prototype), { kernel })
+    assert.equal((await server.resolveLogsRoot({ workspace: 'nested' })).logsRoot, path.resolve(launcher, 'logs'))
+
+    const report = await new AppLogReportService({ registry, kernel }).buildReport({ appId: 'nested', status: { path: workspace, title: 'Nested' } })
+    assert.equal(report.sections[0].script, 'start.js')
+    assert.match(report.markdown, /nested report content/)
+  })
+})
+
+test('nested environment initialization adds parent repository excludes without touching root-layout repositories', async () => {
+  await withHome(async home => {
+    const kernel = kernelFor(home)
+    const nested = path.resolve(home, 'api', 'nested')
+    const root = path.resolve(home, 'api', 'root')
+    await write(nested, 'pinokio/pinokio.js')
+    await fs.mkdir(path.resolve(nested, '.git'), { recursive: true })
+    await write(root, 'pinokio.js')
+    await fs.mkdir(path.resolve(root, 'pinokio'), { recursive: true })
+    await fs.mkdir(path.resolve(root, '.git', 'info'), { recursive: true })
+    await write(root, '.git/info/exclude', 'existing\n')
+
+    await Environment.init({ name: 'nested' }, kernel)
+    assert.match(await fs.readFile(path.resolve(nested, '.git', 'info', 'exclude'), 'utf8'), /^\/pinokio\/ENVIRONMENT$/m)
+
+    await Environment.init({ name: 'root' }, kernel)
+    assert.equal(await fs.readFile(path.resolve(root, '.git', 'info', 'exclude'), 'utf8'), 'existing\n')
+
+    const worktree = path.resolve(home, 'api', 'worktree')
+    await write(worktree, 'pinokio/pinokio.js')
+    await write(worktree, '.git', 'gitdir: /tmp/example\n')
+    await Environment.init({ name: 'worktree' }, kernel)
+    assert.equal(await fs.readFile(path.resolve(worktree, '.git'), 'utf8'), 'gitdir: /tmp/example\n')
+  })
+})